home *** CD-ROM | disk | FTP | other *** search
/ System Booster / System Booster.iso / Texteditors / Origami / Sources / doc / intro.ms < prev    next >
Encoding:
Text File  |  1996-09-27  |  6.6 KB  |  279 lines
  1. .\"{{{}}}
  2. .\"{{{  Notes
  3. .\" nroff -ms intro.ms | more
  4. .ds Tx T\v'2p'E\v'-2p'X
  5. .\"}}}
  6. .\"{{{  Title and Abstract
  7. .TL
  8. Introduction to Folding Editors
  9. .AU
  10. Michael Haardt
  11. .AI
  12. R\(:utscherstra\(sse 155/1703
  13. 52072 Aachen
  14. Germany
  15. (u31b3hs@pool.informatik.rwth-aachen.de)
  16. .AB
  17. This document explains the principles of folding editors in general,
  18. because most people have never used such an editor.  It gives an example of
  19. an Origami editing session to show the advantages of folding program sources.
  20. .AE
  21. .\"}}}
  22. .\"{{{  Introduction
  23. .NH 1
  24. Introduction
  25. .LP
  26. Origami is a
  27. .I folding
  28. .I editor ,
  29. similar to, and inspired by, the editor included in the Inmos TDS
  30. (Transputer Development System).  Those of us who have become familiar
  31. with the TDS editor have long bemoaned the lack of a similar editor for
  32. use with other languages, for example Pascal and C.
  33. .PP
  34. Origami is not a word processor (although many of its features would be
  35. useful in a word processor), but it comes into its own as a program
  36. editor for structured languages and documents.  The structuring of the
  37. code or text is obvious from the screen display (if Origami is sensibly
  38. used!), although no actual code may be visible.
  39. .PP
  40. Existing files, not produced using Origami, may be imported into
  41. Origami, and then folded up for future use, and ease of development.
  42. These files may be further edited either using Origami or some other
  43. editor (if you can bear to use one after Origami!), and compiled in the
  44. normal way.
  45. .PP
  46. A folding editor extends the principle of tree structured directories
  47. to editing text files.  This allows the simultaneous display of large amounts
  48. of text by folding sections of text away behind a descriptive
  49. heading.  This results in a tree structure very similar to a
  50. subdirectory structure of, for example, MINIX.
  51. .PP
  52. By suitable structuring of a text it should be possible, in most
  53. circumstances, to ensure that no display exceeds a single screen at any
  54. time.  To access text which is folded away you can either
  55. .I enter
  56. the containing fold, in which case the contents of the fold and its
  57. header are the only displayed text, or you can
  58. .I open
  59. the fold, in which case the contents are displayed in the context of the
  60. surrounding text.
  61. .PP
  62. The advantage of this system is that it eliminates the need for
  63. seemingly endless paging through long files to find the section of
  64. interest, allowing you to move down the tree structure, following the
  65. (hopefully) descriptive headers to locate the text you require.
  66. .\"}}}
  67. .\"{{{  Examples of Origami folding
  68. .NH 1
  69. Examples of Origami Folding
  70. .LP
  71. As an example, a Pascal file might look like this at
  72. the top level (e.g.\& immediately after starting Origami):
  73. .DS L
  74. program test;
  75. \&...  CONSTs
  76. \&...  TYPEs
  77. \&...  VARs
  78. \&...  procedures
  79. \&...  main body of code
  80. .DE
  81. OPENing the VARs fold might lead to the following display:
  82. .DS L
  83. program test;
  84. \&...  CONSTs
  85. \&...  TYPEs
  86. {\&{\&{  VARs
  87. VAR  i : integer;
  88.      x : real;
  89. }\&}\&}
  90. \&...  procedures
  91. \&...  main body of code
  92. .DE
  93. ENTERing the procedures fold might give:
  94. .DS L
  95. {\&{\&{  procedures
  96. \&...   statistical procedures
  97. \&...   string handling procedures
  98. \&...   procedure user_input
  99. }\&}\&}
  100. .DE
  101. Each of these folds can be
  102. .I entered
  103. further until actual code is reached \(em for example if we
  104. .I enter
  105. the procedure user_input fold we might find:
  106. .DS L
  107. {\&{\&{  procedure user_input
  108. procedure user_input(prompt : str_type; var reply : str_type);
  109. \&...  local declarations
  110. \&...  local procedures
  111.   begin
  112.     repeat
  113.       write(prompt);
  114.       readln(reply);
  115.     until verify_reply(reply);
  116.   end;
  117. }\&}\&}
  118. .DE
  119. Folds can be nested and indented.  It is also possible, to attach a file
  120. to a fold, which means that you enter a fold in your text, which is
  121. stored in another file.  There are utitilies, which create nested file
  122. folds of whole directory trees.  This means, that you can reach all
  123. files of a project in Origami without typing filenames.
  124. .\"}}}
  125. .\"{{{  foldmarks and the comment language
  126. .NH 1
  127. Commenting the fold-structure
  128. .LP
  129. The folds are stored in the text as normal text lines.  Origami can use
  130. one of the following languages, to prevent conflicts with compilers:
  131. ways:
  132. .\"{{{  NONE
  133. .IP None 1.5c
  134. \&{\&{\&{  this is a fold
  135. .br
  136.   \&{\&{\&{F this is a filed fold
  137. .br
  138.   \&:\&:\&:F filename.h
  139. .br
  140.   \&}\&}\&}
  141.   fold-comment and filename are stored in
  142.   two lines, so they can be different!
  143. .br
  144. \&}\&}\&}
  145. .br
  146. .\"}}}
  147. .\"{{{  Occam
  148. .IP Occam 1.5c
  149. --\&{\&{\&{  this is a fold
  150. .br
  151.   --\&{\&{\&{F this is a filed fold
  152. .br
  153.   --\&:\&:\&:F filename.h
  154. .br
  155.   --\&}\&}\&}
  156. .br
  157. --\&}\&}\&}
  158. .br
  159. .\"}}}
  160. .\"{{{  Pascal
  161. .IP Pascal 1.5c
  162. (*\&{\&{\&{  this is a fold *)
  163. .br
  164.   (*\&{\&{\&{F this is a filed fold*)
  165. .br
  166.   (*\&:\&:\&:F filename.h*)
  167. .br
  168.   (*\&}\&}\&}  *)
  169. .br
  170. (*\&}\&}\&}  *)
  171. .br
  172. .\"}}}
  173. .\"{{{  C
  174. .IP C 1.5c
  175. /*\&{\&{\&{  this is a fold*/
  176. .br
  177.   /*\&{\&{\&{F this is a filed fold*/
  178. .br
  179.   /*\&:\&:\&:F filename.h*/
  180. .br
  181.   /*\&}\&}\&}  */
  182. .br
  183. /*\&}\&}\&}  */
  184. .br
  185. .\"}}}
  186. .\"{{{  Lisp
  187. .IP Lisp 1.5c
  188. ;\&{\&{\&{  this is a fold
  189. .br
  190.   ;\&{\&{\&{F this is a filed fold
  191. .br
  192.   ;\&:\&:\&:F filename.h
  193. .br
  194.   ;\&}\&}\&}
  195. .br
  196. ;\&}\&}\&}
  197. .br
  198. .\"}}}
  199. .\"{{{  roff
  200. .IP Roff 1.5c
  201. \&.\e"\&{\&{\&{  this is a fold
  202. .br
  203.   \&.\e"\&{\&{\&{F this is a filed fold
  204. .br
  205.   \&.\e"\&:\&:\&:F filename.h
  206. .br
  207.   \&.\e"\&}\&}\&}
  208. .br
  209. \&.\e"\&}\&}\&}
  210. .br
  211. .\"}}}
  212. .\"{{{  tex
  213. .IP \*(Tx 1.5c
  214. %\&{\&{\&{  this is a fold
  215. .br
  216.   %\&{\&{\&{F this is a filed fold
  217. .br
  218.   %\&:\&:\&:F filename.h
  219. .br
  220.   %\&}\&}\&}
  221. .br
  222. %\&}\&}\&}
  223. .br
  224. .\"}}}
  225. .\"{{{  script
  226. .IP Script 1.5c
  227. #\&{\&{\&{  this is a fold
  228. .br
  229.   \&#\&{\&{\&{F this is a filed fold
  230. .br
  231.   \&#\&:\&:\&:F filename.h
  232. .br
  233.   \&#\&}\&}\&}
  234. .br
  235. #\&}\&}\&}
  236. .br
  237. .\"}}}
  238. .\"{{{  user
  239. .IP User 1.5c
  240. You can specify the start and end of the comment yourself.
  241. .br
  242. @@@\&{\&{\&{  this is a fold$$$
  243. .br
  244.   @@@\&{\&{\&{F this is a filed fold$$$
  245. .br
  246.   @@@\&:\&:\&:F filename.h$$$
  247. .br
  248.   @@@\&}\&}\&}  $$$
  249. .br
  250. @@@\&}\&}\&}  $$$
  251. .br
  252. .\"}}}
  253. .\"{{{  Inmos
  254. .IP Inmos 1.5c
  255. This is a binary format. It can be used, to edit TDS/MultiTool files
  256. without converting them.
  257. .\"}}}
  258. .LP
  259. The marks {\&{\&{, :\&:\&: and }\&}\&} can be replaced by other
  260. characters via command line option.
  261. .\"}}}
  262. .\"{{{  Summary
  263. .NH 1
  264. Summary
  265. .LP
  266. Experience has shown, that a folding editor supports more modular
  267. and well commented source code.  The code has a better structure,
  268. because the structure is obvious.  Editing gets more efficient, because
  269. moving to a particular place in the code is very easy.
  270. .PP
  271. We also use Origami as an editor for \*(Tx and roff documents.
  272. Many people discovered a bad structure in their documents, after they
  273. folded them with Origami.
  274. .PP
  275. The universality of the folding concept allows to use Origami as an
  276. editor for nearly every task.  This means, that we even fold rc files
  277. with it.
  278. .\"}}}
  279.